package cn.edu.cug.cs.gtl.apis.render.paths;

import cn.edu.cug.cs.gtl.apis.render.NativeObjectWrapper;

/*
A path represents a scene graph or subgraph. It contains a list of pointers to nodes forming a chain from some root to some descendent. Each node in the chain is a child of the previous node. Paths are used to refer to some object in a scene graph precisely and unambiguously, even if there are many instances of the object. Therefore, paths are returned by both the SoRayPickAction and SoSearchAction.

When an action is applied to a path, only the nodes in the subgraph defined by the path are traversed. These include : the nodes in the path chain, all nodes (if any) below the last node in the path, and all nodes whose effects are inherited by any of these nodes.

SoPath attempts to maintain consistency of paths even when the structure of the scene graph changes. For example, removing a child from its parent when both are in a path chain cuts the path chain at that point, leaving the top part intact. Removing the node to the left of a node in a path adjusts the index for that node. Replacing a child in the chain with the new child, truncating the path below the new child.

Since nodekits hide their children, there are 3 ways to view the differents nodes contained by the path
the regular path (field regular) do not contains hidden childrens of nodekits
the nodekit path (field nodekit) contains only the nodekits
the full path (field full) contains all nodes (public and hidden)
Thus, for instance,
full.getLength() returns the number of public and hidden nodes in the path
nodekit.getLength() returns the number of nodekits in the path
regular.getLength() returns the number of nodes up to the first nodekit in the path
 */
public interface Path extends NativeObjectWrapper {
    GeneralPath full();
    NodeKitPath nodeKit();
    GeneralPath regular();
}
